<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
                "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
  <title>Description of propval</title>
  <meta name="keywords" content="propval">
  <meta name="description" content="This deals with property/value pairs of optional arguments.">
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  <meta name="generator" content="m2html &copy; 2003 Guillaume Flandin">
  <meta name="robots" content="index, follow">
  <link type="text/css" rel="stylesheet" href="../m2html.css">
</head>
<body>
<a name="_top"></a>
<!-- menu.html . -->
<h1>propval
</h1>

<h2><a name="_name"></a>PURPOSE <a href="#_top"><img alt="^" border="0" src="../up.png"></a></h2>
<div class="box"><strong>This deals with property/value pairs of optional arguments.</strong></div>

<h2><a name="_synopsis"></a>SYNOPSIS <a href="#_top"><img alt="^" border="0" src="../up.png"></a></h2>
<div class="box"><strong>function [combined_struct user_struct undefaulted_struct] = propval(user_propvals,defaults_struct) </strong></div>

<h2><a name="_description"></a>DESCRIPTION <a href="#_top"><img alt="^" border="0" src="../up.png"></a></h2>
<div class="fragment"><pre class="comment"> This deals with property/value pairs of optional arguments.

 [COMBINED_STRUCT USER_STRUCT UNDEFAULTED_STRUCT] = PROPVAL(USER_PROPVALS,DEFAULTS_STRUCT)

 Feed in the varargin cell array and a defaults_struct
 structure. Here's some example code for your function that shows how
 to call propval

 function [blah] = foo(...,varargin)

 defaults_struct.arg1 = 1000;
 defaults_struct.arg2 = 1000;
 ...
 combined_struct = propval(varargin,defaults_struct);

 This also does something else that's clever. If, instead of a
 cell array in propval, you feed in a single struct, this treats
 it as though it's a property/value cell array and continues
 normally. Otherwise, it should error out

 COMBINED_STRUCT will be a structure containing all the properties with the
 user's values, if included, otherwise the defaults that were set
 by the function-writer.

 USER_STRUCT contains just those arguments that the user provided
 in the property/value pairs, just in case you want to know which
 defaults got overwrote.

 UNDEFAULTED_STRUCT contains just those arguments where the user
 provided a property/value pair for which no default was provided,
 as a flag to the function-writer and user that there may be a
 typo or confusion about which property/value pairs are
 allowed. The UNDEFAULTED_STRUCT property/value pairs still get
 included in COMBINED_STRUCT just in case.

 This script also does some error-checking to make sure that all
 user-defined properties have defaults, that no property gets set
 twice etc. Note that this doesn't care what order the properties
 are inputted, as long as they're in property/value pairs.

 This doesn't check that that the variable types are the same for
 a given property in user_propvals and the default_struct

 e.g. look at the resulting args in this case:
   varargin = {'first_prop',2000,'second_prop',5000};
   defaults.first_prop = 1000;
   defaults.second_prop = 1000;
   defaults.third_prop = 1000;
   args = propval(varargin,defaults);</pre></div>

<!-- crossreference -->
<h2><a name="_cross"></a>CROSS-REFERENCE INFORMATION <a href="#_top"><img alt="^" border="0" src="../up.png"></a></h2>
This function calls:
<ul style="list-style-image:url(../matlabicon.gif)">
</ul>
This function is called by:
<ul style="list-style-image:url(../matlabicon.gif)">
<li><a href="create_pattern_from_mask.html" class="code" title="function [subj] = create_pattern_from_mask(subj,old_patname,maskname,new_patname,varargin)">create_pattern_from_mask</a>	Creates a new pattern by masking an old one</li><li><a href="create_thresh_mask.html" class="code" title="function [subj] = create_thresh_mask(subj,map_patname,new_maskname,thresh,varargin)">create_thresh_mask</a>	Create a boolean mask by thresholding a statmap</li><li><a href="create_xvalid_indices.html" class="code" title="function [subj] = create_xvalid_indices(subj,runs_selname,varargin)">create_xvalid_indices</a>	Creates a selector for each iteration for leave-one-out cross-validation.</li><li><a href="cross_validation.html" class="code" title="function [subj results] = cross_validation(subj,patname,regsname,selgroup,maskgroup,class_args,varargin)">cross_validation</a>	Cross-validation classification</li><li><a href="feature_select.html" class="code" title="function [subj] = feature_select(subj,data_patname,regsname,selsgroup,varargin)">feature_select</a>	No-peeking feature selection</li><li><a href="get_number.html" class="code" title="function [objno] = get_number(subj,objtype,objname,varargin)">get_number</a>	Internal function - find the cell index of an object</li><li><a href="init_subj.html" class="code" title="function [subj] = init_subj(exp_name,id,varargin)">init_subj</a>	Returns an empty initialized SUBJ structure</li><li><a href="move_pattern_to_hd.html" class="code" title="function [subj pathfilename] = move_pattern_to_hd(subj,patname,varargin)">move_pattern_to_hd</a>	Moves the pattern MAT to the hard disk</li><li><a href="peek_feature_select.html" class="code" title="function [subj] = peek_feature_select(subj,data_patname,regsname,selname,varargin)">peek_feature_select</a>	Just like PEEK_FEATURE_SELECT, except that it peeks</li><li><a href="remove_object.html" class="code" title="function [subj] = remove_object(subj,objtype,objname,varargin)">remove_object</a>	This removes an object permanently</li><li><a href="save_subj.html" class="code" title="function [subj fn] = save_subj(subj,varargin)">save_subj</a>	This just saves the subj structure to a file.</li><li><a href="scramble_regressors.html" class="code" title="function [subj] = scramble_regressors(subj,regsname,selname,new_regsname,varargin)">scramble_regressors</a>	Scrambles your regressors for sanity-checking</li><li><a href="set_mat.html" class="code" title="function [subj] = set_mat(subj,objtype,objname,newmat,varargin)">set_mat</a>	Updates the MAT contents of an object</li><li><a href="set_objfield.html" class="code" title="function [subj] = set_objfield(subj,objtype,objname,fieldname,newval,varargin)">set_objfield</a>	Replace or add a field to an object</li><li><a href="set_objsubfield.html" class="code" title="function [subj] = set_objsubfield(subj,objtype,objname,fieldname,subfieldname,newval,varargin)">set_objsubfield</a>	Sets the subfield of the object to NEWVAL.</li><li><a href="summarize.html" class="code" title="function [] = summarize(subj,varargin)">summarize</a>	Prints info about the contents of the subj structure</li><li><a href="write_to_afni.html" class="code" title="function [err] = write_to_afni(subj, objtype, objname, sample_filename, varargin)">write_to_afni</a>	Writes an object to a file, using the header info from a specified file.</li></ul>
<!-- crossreference -->


<h2><a name="_source"></a>SOURCE CODE <a href="#_top"><img alt="^" border="0" src="../up.png"></a></h2>
<div class="fragment"><pre>0001 <a name="_sub0" href="#_subfunctions" class="code">function [combined_struct user_struct undefaulted_struct] = propval(user_propvals,defaults_struct)</a>
0002 
0003 <span class="comment">% This deals with property/value pairs of optional arguments.</span>
0004 <span class="comment">%</span>
0005 <span class="comment">% [COMBINED_STRUCT USER_STRUCT UNDEFAULTED_STRUCT] = PROPVAL(USER_PROPVALS,DEFAULTS_STRUCT)</span>
0006 <span class="comment">%</span>
0007 <span class="comment">% Feed in the varargin cell array and a defaults_struct</span>
0008 <span class="comment">% structure. Here's some example code for your function that shows how</span>
0009 <span class="comment">% to call propval</span>
0010 <span class="comment">%</span>
0011 <span class="comment">% function [blah] = foo(...,varargin)</span>
0012 <span class="comment">%</span>
0013 <span class="comment">% defaults_struct.arg1 = 1000;</span>
0014 <span class="comment">% defaults_struct.arg2 = 1000;</span>
0015 <span class="comment">% ...</span>
0016 <span class="comment">% combined_struct = propval(varargin,defaults_struct);</span>
0017 <span class="comment">%</span>
0018 <span class="comment">% This also does something else that's clever. If, instead of a</span>
0019 <span class="comment">% cell array in propval, you feed in a single struct, this treats</span>
0020 <span class="comment">% it as though it's a property/value cell array and continues</span>
0021 <span class="comment">% normally. Otherwise, it should error out</span>
0022 <span class="comment">%</span>
0023 <span class="comment">% COMBINED_STRUCT will be a structure containing all the properties with the</span>
0024 <span class="comment">% user's values, if included, otherwise the defaults that were set</span>
0025 <span class="comment">% by the function-writer.</span>
0026 <span class="comment">%</span>
0027 <span class="comment">% USER_STRUCT contains just those arguments that the user provided</span>
0028 <span class="comment">% in the property/value pairs, just in case you want to know which</span>
0029 <span class="comment">% defaults got overwrote.</span>
0030 <span class="comment">%</span>
0031 <span class="comment">% UNDEFAULTED_STRUCT contains just those arguments where the user</span>
0032 <span class="comment">% provided a property/value pair for which no default was provided,</span>
0033 <span class="comment">% as a flag to the function-writer and user that there may be a</span>
0034 <span class="comment">% typo or confusion about which property/value pairs are</span>
0035 <span class="comment">% allowed. The UNDEFAULTED_STRUCT property/value pairs still get</span>
0036 <span class="comment">% included in COMBINED_STRUCT just in case.</span>
0037 <span class="comment">%</span>
0038 <span class="comment">% This script also does some error-checking to make sure that all</span>
0039 <span class="comment">% user-defined properties have defaults, that no property gets set</span>
0040 <span class="comment">% twice etc. Note that this doesn't care what order the properties</span>
0041 <span class="comment">% are inputted, as long as they're in property/value pairs.</span>
0042 <span class="comment">%</span>
0043 <span class="comment">% This doesn't check that that the variable types are the same for</span>
0044 <span class="comment">% a given property in user_propvals and the default_struct</span>
0045 <span class="comment">%</span>
0046 <span class="comment">% e.g. look at the resulting args in this case:</span>
0047 <span class="comment">%   varargin = {'first_prop',2000,'second_prop',5000};</span>
0048 <span class="comment">%   defaults.first_prop = 1000;</span>
0049 <span class="comment">%   defaults.second_prop = 1000;</span>
0050 <span class="comment">%   defaults.third_prop = 1000;</span>
0051 <span class="comment">%   args = propval(varargin,defaults);</span>
0052 
0053 <span class="comment">% This is part of the Princeton MVPA toolbox, released under the</span>
0054 <span class="comment">% GPL. See http://www.csbmb.princeton.edu/mvpa for more</span>
0055 <span class="comment">% information.</span>
0056 
0057 
0058 <span class="comment">% Error Checking</span>
0059 <span class="keyword">if</span> ~iscell(user_propvals)
0060   error(<span class="string">'User_Propvals should be a cell array, like varargin'</span>);
0061 <span class="keyword">end</span>
0062 <span class="keyword">if</span> isempty(defaults_struct)
0063   error(<span class="string">'You have to feed in some defaults if you''re going to use optional arguments. Set them to [] if you don''t care'</span>);
0064 <span class="keyword">end</span>
0065 <span class="keyword">if</span> ~isstruct(defaults_struct)
0066   error(<span class="string">'Defaults_struct has to be a struct'</span>);
0067 <span class="keyword">end</span>
0068 
0069 <span class="comment">% Determine the number of default fields</span>
0070 default_fieldnames = fieldnames(defaults_struct);
0071 n_defaults = length(default_fieldnames);
0072 
0073 <span class="comment">% Initialize the combined structure to default values</span>
0074 combined_struct = defaults_struct;
0075 user_struct = [];
0076 undefaulted_struct = [];
0077 
0078 n_user_propvals = length(user_propvals);
0079 
0080 <span class="comment">% Determine whether the user arguments are in struct form or</span>
0081 <span class="comment">% prop/val form.  If they are in struct form, convert to prop/val</span>
0082 <span class="comment">% form</span>
0083 
0084 <span class="keyword">if</span> n_user_propvals == 1
0085   <span class="keyword">if</span> isstruct(user_propvals{1})
0086     input_struct = user_propvals{1};
0087   <span class="keyword">else</span>
0088     error(<span class="string">'Single non-struct argument passed to propval'</span>);
0089   <span class="keyword">end</span>
0090   
0091   user_propvals = {};
0092   input_fields = fieldnames(input_struct);
0093   <span class="keyword">for</span> i=1:length(input_fields)
0094     user_propvals{(i-1)*2+1} = input_fields{i};
0095     user_propvals{i*2}       = getfield(input_struct, input_fields{i});
0096   <span class="keyword">end</span>
0097   
0098   n_user_propvals = length(user_propvals);
0099   
0100 <span class="keyword">elseif</span> mod(n_user_propvals,2)
0101   error(<span class="string">'The property/value arguments have to come in pairs - but this is an odd number of arguments'</span>);  
0102 <span class="keyword">end</span>
0103 
0104 <span class="keyword">for</span> a = 1:2:n_user_propvals
0105   
0106   cur_prop = user_propvals{a};
0107   cur_val = user_propvals{a+1};
0108 
0109   <span class="keyword">if</span> ~ischar(cur_prop)
0110     error(<span class="string">'This property name is not a string'</span>);
0111   <span class="keyword">end</span>
0112     
0113   <span class="keyword">if</span> ~strcmp(cur_prop,lower(cur_prop))
0114     warning(<span class="string">'All optional arguments should be lower case - fixed for you'</span>);
0115     cur_prop = lower(cur_prop);
0116   <span class="keyword">end</span>
0117 
0118   <span class="keyword">if</span> isfield(user_struct,cur_prop)
0119     error(<span class="string">'You''ve provided two property/value pairs for the same property'</span>);
0120   <span class="keyword">end</span>
0121   
0122   <span class="keyword">if</span> ~isfield(defaults_struct,cur_prop)
0123     warning(<span class="string">'The user provided a property/value pair for which there is no default'</span>);
0124     undefaulted_struct.(cur_prop) = cur_val;
0125   <span class="keyword">end</span>
0126   
0127   user_struct.(cur_prop) = cur_val;
0128   combined_struct.(cur_prop) = cur_val;
0129 <span class="keyword">end</span> <span class="comment">% a n_user_propvals</span>
0130 
0131 
0132 
0133</pre></div>
<hr><address>Generated on Tue 06-Sep-2005 22:11:31 by <strong><a href="http://www.artefact.tk/software/matlab/m2html/" target="_parent">m2html</a></strong> &copy; 2003</address>
</body>
</html>